Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
@npmcli/promise-spawn
Advanced tools
The @npmcli/promise-spawn package is designed to execute shell commands or scripts with a promise-based interface. It simplifies working with child processes in Node.js by providing a straightforward way to spawn processes and handle their output, errors, and exit codes asynchronously. This package is particularly useful for building Node.js applications that need to interact with the system's shell or execute external commands as part of their operation.
Executing a simple command
This feature allows you to execute a simple command (in this case, 'echo') and print its output, error output, and exit code. The 'stdioString' option is used to treat the output and error as strings.
const promiseSpawn = require('@npmcli/promise-spawn');
async function runCommand() {
const { stdout, stderr, code } = await promiseSpawn('echo', ['Hello, world!'], { stdioString: true });
console.log(`Output: ${stdout}`);
console.error(`Error: ${stderr}`);
console.log(`Exit code: ${code}`);
}
runCommand();
Executing a command with error handling
This feature demonstrates executing a command that is expected to fail (attempting to list a nonexistent directory) and handling the error gracefully. The catch block captures the error, allowing the application to respond appropriately.
const promiseSpawn = require('@npmcli/promise-spawn');
async function runCommandWithErrorHandling() {
try {
const { stdout } = await promiseSpawn('ls', ['-l', '/nonexistent'], { stdioString: true });
console.log(`Output: ${stdout}`);
} catch (err) {
console.error(`Error: ${err.message}`);
}
}
runCommandWithErrorHandling();
Execa is a popular alternative to @npmcli/promise-spawn for executing shell commands. It offers a richer API, including support for synchronous execution, better Windows support, and more detailed control over the child process. Compared to @npmcli/promise-spawn, execa might be preferred for more complex use cases requiring these additional features.
Child-process-promise provides promise-based wrappers for the Node.js child_process module functions. Similar to @npmcli/promise-spawn, it simplifies working with child processes by returning promises. However, it sticks closer to the original Node.js API, making it a good choice for those who prefer a minimal abstraction layer.
Spawn processes the way the npm cli likes to do. Give it some options, it'll give you a Promise that resolves or rejects based on the results of the execution.
Note: When the current user is root, this will use
infer-owner
to find the owner of the current
working directory, and run with that effective uid/gid. Otherwise, it runs
as the current user always. (This helps prevent doing git checkouts and
such, and leaving root-owned files lying around in user-owned locations.)
const promiseSpawn = require('@npmcli/promise-spawn')
promiseSpawn('ls', [ '-laF', 'some/dir/*.js' ], {
cwd: '/tmp/some/path', // defaults to process.cwd()
stdioString: false, // stdout/stderr as strings rather than buffers
stdio: 'pipe', // any node spawn stdio arg is valid here
// any other arguments to node child_process.spawn can go here as well,
// but uid/gid will be ignored and set by infer-owner if relevant.
}, {
extra: 'things',
to: 'decorate',
the: 'result',
}).then(result => {
// {code === 0, signal === null, stdout, stderr, and all the extras}
console.log('ok!', result)
}).catch(er => {
// er has all the same properties as the result, set appropriately
console.error('failed!', er)
})
promiseSpawn(cmd, args, opts, extra)
-> Promise
Run the command, return a Promise that resolves/rejects based on the process result.
Result or error will be decorated with the properties in the extra
object. You can use this to attach some helpful info about why the
command is being run, if it makes sense for your use case.
If stdio
is set to anything other than 'inherit'
, then the result/error
will be decorated with stdout
and stderr
values. If stdioString
is
set to true
, these will be strings. Otherwise they will be Buffer
objects.
Returned promise is decorated with the stdin
stream if the process is set
to pipe from stdin
. Writing to this stream writes to the stdin
of the
spawned process.
stdioString
Boolean, default false
. Return stdout/stderr output as
strings rather than buffers.cwd
String, default process.cwd()
. Current working directory for
running the script. Also the argument to infer-owner
to determine
effective uid/gid when run as root on Unix systems.child_process.spawn
can be passed as well, but
note that uid
and gid
will be overridden by the owner of the cwd when
run as root on Unix systems, or null
otherwise.FAQs
spawn processes the way the npm cli likes to do
We found that @npmcli/promise-spawn demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.